Thank you @leandrodamascena ! Few questions/comments:

• 1. XSS in remark-mermaid plugin

  docs/plugins/remark-mermaid.mjs:8 interpolates node.value directly into HTML
  with no escaping:

  value: <pre class="mermaid">${node.value}</pre>,

  A mermaid code block containing <script>alert('xss')</script>

   would
  
  be rendered as executable HTML. Yes, this is a docs site built from trusted
  
  source files today — but this is a security-focused project ("ABCA agents
  
  execute code with repository access"). The docs should model the security
  
  posture they describe.
  
  Fix: HTML-entity-escape node.value before interpolation, or use a
  
  well-maintained plugin like rehype-mermaid instead.
  

• 2. Unpinned CDN dependency with no SRI

  "import mermaid from
  'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs'"

  Three problems:

  • Loose version pin — mermaid@11 resolves to latest 11.x. A breaking minor
    release silently breaks diagrams.
  • No integrity attribute — A compromised jsDelivr CDN injects arbitrary JS into
    the docs site.
  • No crossorigin attribute — Needed for SRI to work.

  For a project whose SECURITY.md discusses "defense in depth" and DNS Firewall,
  shipping an unpinned, unverified third-party script is incongruent.

  Fix: Pin to exact version (e.g., mermaid@11.4.1), add integrity hash, or
  self-host the library.

• 3. Orphaned files not in sidebar

  Two files exist in the rendered output but are unreachable from navigation:

  • using/Introduction.md — A 5-line stub ("Using the platform") with no useful
    content.
  • using/Prerequisites.md — Renamed from user-guide/Prerequisites.md but content
    absorbed into Quick Start.

  These will be deployed, indexable by search engines, and confusing to anyone who
  lands on them.

  Fix: Delete both files, or add a redirect/note pointing to the correct location.

• 4. Source directory naming mismatch

  The source directory is still docs/design/ on disk, but it renders at
  /architecture/. The sync script handles this mapping, but a future contributor
  editing docs/design/COMPUTE.md may not realize it appears as
  /architecture/compute on the site.

  Fix: Either rename the source directory to docs/architecture/ for alignment, or
  add a comment at the top of the sync script explaining the mapping.

• 5. Sidebar slug mismatch — "Customizing" section mixes paths

  label: 'Customizing',
  items: [
  { slug: 'using/repository-onboarding' }, // ← lives under using/
  { slug: 'using/per-repo-overrides' }, // ← lives under using/
  { label: 'Prompt Engineering', slug: 'customizing/prompt-engineering' }, // ←
  lives under customizing/
  ],

  Two of three items under "Customizing" are actually in the using/ URL path. This
  means:

  • Breadcrumbs may show the wrong hierarchy
  • A user navigating via URL structure (/using/repository-onboarding) won't find
    the page in the sidebar's "Using the Platform" section where they'd expect it

  Fix: Either move Repository-onboarding.md and Per-repo-overrides.md to
  customizing/, or put them in the "Using the Platform" sidebar section and keep
  "Customizing" focused on prompt engineering.

• 6. Incomplete anchor route mapping in sync script

  docs/scripts/sync-starlight.mjs maps only 3 USER_GUIDE anchors to the new using/
  structure:

  const userGuideAnchorRoutes = {
  authentication: '/using/authentication',
  'repository-onboarding': '/using/repository-onboarding',
  'task-lifecycle': '/using/task-lifecycle',
  };

  The old USER_GUIDE had many more sections (CLI, REST API, webhooks, tips, task
  types, per-repo config). Any existing link like USER_GUIDE.md#using-the-cli will
  now fall through to /using/overview#using-the-cli, which doesn't resolve.

  Fix: Audit all anchors in the old USER_GUIDE and add mappings for the ones that
  moved to standalone pages.

Also, I think this will impact the abca-plugin. Since the setup skill walks users through initial deployment, it should point them to the new Quick Start rather than the old user guide introduction

Thanks @krokoko for the feedback.

1) XSS in remark-mermaid - done

2) CDN pin - done

3) Orphaned files - Deleted. Added cleanup logic in the sync script so they don't regenerate.

4) Source dir naming - Added a comment in the sync script explaining the docs/design/ -> /architecture/ mapping and why we keep the source directory name.

5) Sidebar slug mismatch - Moved Repository-onboarding.md and Per-repo-overrides.md to customizing/. All three items in the Customizing sidebar section now live under the same URL path.

6) Anchor mapping - Added all missing USER_GUIDE anchors (overview, task-types, using-the-cli, using-the-rest-api, webhook-integration, what-the-agent-does, tips-for-being-a-good-citizen, per-repo-overrides, repository-onboarding).

Plugin impact - Good catch. Updated abca-plugin/skills/setup/SKILL.md to point to /getting-started/quick-start/ instead of the old /user-guide/introduction/.